home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / util / cli / man379.lha / man379.doc < prev    next >
Text File  |  1995-02-03  |  6KB  |  158 lines
  1.  
  2.                         ___
  3. __      __   __    _     /|
  4. ||\ |\  ||\  ||\   |  /\/ |  The Manual System (Yet Another... but Better!)
  5. || \| \ || \ || \  | /  \
  6. ||  \  \||==\||  \ | \  /  Release 37.9 [first public] - 04 February 1995
  7. ||   \  \|   \|   \|  \/   Copyright 1995 Ben R. Kennedy; all rights reserved!
  8.  
  9.  
  10.  
  11.         BRIEF TABLE OF CONTENTS
  12.         =======================
  13.  
  14.         1. About this documentation
  15.         2. What is MAN?  How come?
  16.         3. Installation & Using it
  17.         4. Neat features & config notes
  18.         5. Creating/modifying man pages
  19.         6. Internal format for MAN pages
  20.         7. How to contact me
  21.  
  22. NOTE: MAN IS FREEWARE.  That means that you are free to use and to distribute
  23. it to whomever you please, so long as this archive remains more or less intact
  24. and that no charge is levied for my work!
  25.  
  26.  
  27. 1. ABOUT THIS DOCUMENTATION
  28. ---------------------------
  29.  
  30. The doc file you are reading now is fairly brief; I currently suffer from a
  31. semi-moderate case of Too Busy Schedulitis so will write more complete docs
  32. as time (and interest) warrant!
  33.  
  34. This as you have deduced is a plain old ascii doc (not a man page).  However,
  35. individual man pages for the included utilities can be found in the man/
  36. dir of this archive, along with their "mandoc" counterparts.  See these for
  37. detailed info.
  38.  
  39.  
  40. 2. WHAT IS MAN?  HOW COME?
  41. --------------------------
  42.  
  43. The Manual System (MAN) is supposed to provide an easy way for finding and
  44. referring to computer-related documentation, such as C function autodocs and
  45. reference, shell commands, reference tables, and so on.  The purpose is pretty
  46. much the same as that for the Unix original: to eliminate (or serve as a
  47. complement to) cumbersome manuals and piles of paper!
  48.  
  49. I was motivated to write my own MAN system in December/94 after I became tired
  50. of having to fire up AmigaGuide (and 730 k of docs) to look up a simple proto
  51. for a function or two when programming.  It occurred to me that if I could
  52. simply type "man fseek" and be provided with complete info for that function,
  53. so much time and effort would be saved!
  54.  
  55. As I am aware there are a couple other MAN type things on Aminet, and this one
  56. isn't meant as competition or replacement for them (I haven't even used
  57. another).  I wrote it however to serve my immediate needs, and with the intent-
  58. tion of making it as portable and flexible as possible; therefore, I see no
  59. reason why it could not come to serve all needs.  Read on :-)
  60.  
  61.  
  62. 3. INSTALLATION & USING IT
  63. --------------------------
  64.  
  65. To install everything: take a look at the install.sh batch file and make
  66. sure you know what's going on (make any site-specific changes if needed), then
  67. run it -- it will install what's here.  Don't forget to add an ASSIGN to your
  68. user-startup manually!
  69.  
  70. There are a few programs included in the bin/ dir of this archive (yeah, I
  71. like Unix names).  Their purposes are as follows:
  72.  
  73.     man - the MAN-page viewer and formatting client.
  74.     doc2man - converts text files into MAN-format manual pages.
  75.     man2doc - reverts MAN-format pages into ascii editable docs.
  76.     guide2man - converts SAS/C AmigaGuide help to MAN pages.
  77.  
  78. For detailed instructions on each command, please take a look at their indivi-
  79. dual manual pages or doc files.  If installed, just type "man <programname>"!
  80.  
  81.  
  82. 4. NEAT FEATURES & CONFIG NOTES
  83. -------------------------------
  84.  
  85. MAN relies on the "more" utility to be present in the search path to page its
  86. converted files to the screen.  This allows customization of the paging
  87. routine if so desired.  At present, the util name is not changeable.
  88.  
  89. MAN will test the existence of an environment variable (local OR global)
  90. called "console_width" for the width of your window, in columns.  Use this
  91. to overried the default setting of a regular 80-col screen.  This determines
  92. how wide to format the text.
  93.  
  94. MAN will automatically justify text and format paragraphs based on the environ-
  95. ment... no special considerations needed when writing the man page!
  96.  
  97.  
  98. 5. CREATING/MODIFYING MAN PAGES
  99. -------------------------------
  100.  
  101. It is easiest if you take a look at the supplied <foo>.doc files to get an
  102. idea of the format for "mandoc" (ascii format interpretable by man2doc) files.
  103. To write a manual page for something has been made as easy as possible with
  104. the intelligent doc2man utility; a doc can be typed by a human and then easily
  105. converted into an encoded manpage format!
  106.  
  107. To modify an existing man page, simply extract the text to an editable "mandoc"
  108. format with man2doc util, edit it to your preference, and then re-encode it
  109. with doc2man.
  110.  
  111. The SAS/C AmigaGuide help files on the C function library can be broken down
  112. into individual man pages (about 400 files, total about 460 kb) by using the
  113. special guide2man util -- see its man page for info.
  114.  
  115.  
  116. 6. INTERNAL FORMAT FOR MAN PAGES
  117. --------------------------------
  118.  
  119. Following is a brief description of the MAN file format, of interest to progr-
  120. ammers writing their own supplementary utils, or merely interested in picking
  121. things apart :-)
  122.  
  123. First longword: identifying string; MAN%c where %c is a version identifier.
  124. Next, any other header info terminated by a NULL (at present, none, i.e. just
  125. a '\0' byte).
  126.  
  127. Following this is the actual body of the file.  It is broken into subsections,
  128. each of which starts with a byte indentifying its type (e.g. 'D' = descrip,
  129. 'S' = synopsis, and so on).  After this byte comes the contents of the section
  130. terminated by a NULL.  Paragraphs should contain '\n' only at end, since MAN
  131. will automatically justify and break lines accordingly.
  132.  
  133. The file ends with another NULL byte (i.e. a subsection identifier of '\0').
  134.  
  135.  
  136. 7. HOW TO CONTACT ME
  137. --------------------
  138.  
  139. First I'd like to say: please do contact me if you have any suggestions or bug
  140. reports.  I will also consider releasing source code to anyone interested in
  141. either improving it, or simply how it works.  I'd like my efforts to be of use
  142. to others.
  143.  
  144. Paper: Ben Kennedy, PO Box 152, Deep River Ontario, Canada K0J 1P0.
  145. Email: aw785@freenet.carleton.ca
  146. Phone: +1-613-584-1587   Fax and BBS (autodetect): +1-613-584-1426.
  147.  
  148.  
  149. That's it for now... hope you find this program useful.
  150.  
  151.     Also a quick greet to Charlotte, one special girl for whom
  152.     I'll never meet a perfect alternate.  ILY Tanda...
  153.  
  154.  
  155.                         ...ben,  February 1995
  156.  
  157.  
  158.